using System;

namespace WenYu.Runtime
{
    /// <summary>
    /// 标准库接口 - 定义所有标准库函数
    /// 
    /// 支持多个实现:
    /// - YouthLibrary: 青春版（教学友好，详细错误信息）
    /// - ProfessionalLibrary: 专业版（严格模式，预留Phase 2+）
    /// 
    /// 对标需求: REQ-05 标准库接口, REQ-06 青春版标准库
    /// </summary>
    public interface IStandardLibrary
    {
        /// <summary>
        /// 输出函数
        /// </summary>
        /// <param name="context">执行上下文（包含要输出的栈顶值）</param>
        /// <param name="count">要输出的值个数</param>
        /// <remarks>
        /// 从操作数栈弹出count个值并输出到控制台。
        /// 值按照入栈顺序输出，中间无分隔符。
        /// </remarks>
        void Print(ExecutionContext context, int count);

        /// <summary>
        /// 输入函数（预留）
        /// </summary>
        /// <remarks>
        /// Phase 2+ 功能
        /// </remarks>
        Value Read();

        /// <summary>
        /// 确认函数 - 显示提示并等待用户输入是/否
        /// </summary>
        /// <param name="prompt">提示信息</param>
        /// <returns>返回真假值（是=真真，否=假假）</returns>
        /// <remarks>
        /// 青春版：支持多种输入格式（是/否、y/n、1/0等）
        /// 自动容错和重试
        /// </remarks>
        Value Confirm(string prompt);

        /// <summary>
        /// 输入带提示 - 显示提示信息后等待用户输入
        /// </summary>
        /// <param name="prompt">提示信息</param>
        /// <returns>返回用户输入的字符串</returns>
        /// <remarks>
        /// Phase 2 功能
        /// </remarks>
        Value ReadWithPrompt(string prompt);

        /// <summary>
        /// 输入带默认值 - 如果用户直接回车则使用默认值
        /// </summary>
        /// <param name="defaultValue">默认值</param>
        /// <returns>返回用户输入或默认值</returns>
        /// <remarks>
        /// Phase 2 功能（可选）
        /// </remarks>
        Value ReadWithDefault(Value defaultValue);

        /// <summary>
        /// 类型转换：转换为文字
        /// </summary>
        Value ToString(Value value);

        /// <summary>
        /// 获取数组长度（预留）
        /// </summary>
        /// <remarks>
        /// Phase 2+ 功能
        /// </remarks>
        Value GetLength(Value arrayValue);

        /// <summary>
        /// 获取字符串长度
        /// </summary>
        Value StringLength(Value stringValue);

        /// <summary>
        /// 错误处理钩子（青春版特有）
        /// </summary>
        /// <param name="message">错误消息</param>
        /// <param name="context">执行上下文（可用于调试）</param>
        /// <remarks>
        /// 青春版可能提供详细的错误建议
        /// 专业版可能抛出异常
        /// </remarks>
        void HandleError(string message, ExecutionContext context);
    }
}
